8.1 - What Your Bot Sees That a Human Can't - API Advantages

Your bot is not a human. It "sees" the game through a direct data feed from the StarCraft II API, giving it several inherent perceptual advantages. These are not cheats; they are natural consequences of the API's design. Understanding these advantages is crucial because it frees you from writing complex code to simulate abilities your bot already has.

Your bot is, in essence, a perfect observer of all visible information. Its challenge is not in perceiving the game, but in making intelligent decisions based on the perfect data it receives.

The Human vs. The Bot: A Perceptual Comparison

+------------------------------------------+       +-----------------------------------------+
|                Human Player              |       |               Your Bot                  |
|==========================================|       |=========================================|
|  - Vision is a fuzzy, analog signal.     |       |  - Vision is a discrete, digital grid.  |
|  - Relies on visual cues (shimmers).     |       |  - Gets exact unit data instantly.      |
|  - Memory is fallible.                   |       |  - Memory is perfect (via unit tags).   |
|  - Calculations are approximate.         |       |  - Calculations are flawless.           |
|  - Reaction time is measured in ms.      |       |  - Reaction time is near-instant.       |
+------------------------------------------+       +-----------------------------------------+

Key API Advantages

Advantage	Human Limitation	Your Bot's Reality	Developer Takeaway
1. Perfect Detection	Must visually spot the "shimmer" of a cloaked unit. May be fooled by a Changeling's disguise, at least temporarily.	If a detector (e.g., Observer, Raven, Spore Crawler) makes a cloaked unit visible, your bot instantly knows its `type_id` and exact `position`. It cannot be tricked by a Changeling once it has been revealed.	You don't need to write code to "detect" shimmers. You only need to write logic to bring a detector and then react to the perfectly-provided information.
2. Flawless Memory	May forget which units were in a specific army or lose track of a key enemy unit that moved out of vision.	Every unit has a permanent `tag`. Your bot can track a specific enemy unit for the entire game, even if it disappears and reappears.	Use `unit.tag` to track high-value targets. You will always know if it's the same unit you saw earlier.
3. Instantaneous Calculation	Must estimate attack ranges and splash damage radii, leading to errors in positioning.	The bot can use `unit.target_in_range()` and pre-programmed splash data to calculate threats with perfect precision.	Trust the API for range checks. Your kiting and positioning logic can be pixel-perfect.
4. Zero Latency Commands	Has a physical and mental delay between seeing an event and reacting to it.	Your bot can issue a command in the same game step it receives the data, allowing for reactions impossible for a human.	Your micro-management logic can be incredibly responsive (e.g., splitting units the instant a projectile is fired).

Developer's Checklist: Leveraging API Advantages

When designing your bot's logic, remember what you get for free:

Don't code a "shimmer detector." The API gives you no data on shimmers. Focus on getting a detector to the right place; the API will do the rest.
Don't assume you can see through disguises. A Changeling will report the type_id it's disguised as. React to it once it's revealed (by damage, detection, or transformation).
Trust the tag. Use it to maintain a "most wanted" list of dangerous enemy units.
Trust the math. Use the provided distance and range functions to build precise micro-management routines.

Code Example: The "All-Seeing" Bot

This bot demonstrates how to leverage these API advantages. It instantly identifies cloaked units and Changelings once they are properly revealed and logs them.

# all_seeing_bot.py

from sc2 import maps
from sc2.bot_ai import BotAI
from sc2.data import Difficulty, Race
from sc2.main import run_game
from sc2.player import Bot, Computer
from sc2.ids.unit_typeid import UnitTypeId as Id

class AllSeeingBot(BotAI):
    """A bot that demonstrates the API's perceptual advantages."""

    def __init__(self):
        super().__init__()
        # Use sets for fast, duplicate-free tracking of seen units.
        self.seen_cloaked_tags = set()
        self.seen_changeling_tags = set()

    async def on_step(self, iteration: int):
        # Loop through all VISIBLE enemy units on every step.
        # This list only includes units that are not cloaked or have been revealed by a detector.
        for enemy in self.enemy_units:
            # ADVANTAGE 1: PERFECT DETECTION OF REVEALED CLOAKED UNITS
            # If a detector is present, the bot instantly knows the unit is cloaked.
            if enemy.is_cloaked and enemy.tag not in self.seen_cloaked_tags:
                self.seen_cloaked_tags.add(enemy.tag)
                print(f"[{self.time_formatted}] API ADVANTAGE: Instantly detected a cloaked {enemy.name} at {enemy.position.rounded} because a detector was present.")

            # ADVANTAGE 2: PERFECT DETECTION OF REVEALED CHANGELINGS
            # The bot knows the unit's true type_id once it is revealed.
            if enemy.type_id == Id.CHANGELING and enemy.tag not in self.seen_changeling_tags:
                self.seen_changeling_tags.add(enemy.tag)
                print(f"[{self.time_formatted}] API ADVANTAGE: Instantly identified a revealed Changeling at {enemy.position.rounded}.")

        # ADVANTAGE 3 & 4: FLAWLESS CALCULATION AND REACTION
        # This logic demonstrates perfect kiting, a feat of calculation and reaction.
        # Each marine will react to the closest threat to it.
        if self.units(Id.MARINE).exists and self.enemy_units.exists:
            for marine in self.units(Id.MARINE):
                closest_enemy = self.enemy_units.closest_to(marine)
                # If weapon is on cooldown, move away
                if marine.weapon_cooldown > 0:
                    marine.move(marine.position.towards(closest_enemy.position, -1))
                # Otherwise, attack
                else:
                    marine.attack(closest_enemy)


if __name__ == "__main__":
    run_game(
        maps.get("GresvanAIE"),
        [
            Bot(Race.Terran, AllSeeingBot()),
            # We use a Zerg opponent because they have access to both cloaked units (Lurkers, Infestors) and changelings.
            Computer(Race.Zerg, Difficulty.Medium)
        ],
        realtime=True,
    )

The Human vs. The Bot: A Perceptual Comparison​

Key API Advantages​

Developer's Checklist: Leveraging API Advantages​

Code Example: The "All-Seeing" Bot​

The Human vs. The Bot: A Perceptual Comparison

Key API Advantages

Developer's Checklist: Leveraging API Advantages

Code Example: The "All-Seeing" Bot